The X-Philes (2nd Revision)/The X-Philes Number 1 (1995).iso/xphiles/hp48_2/hprpldev.tar/usrlib.doc

Text File | 1991-07-12 | 23KB | 728 lines

                    Instructions for MS-DOS program "USRLIB"

       *****************************************************************
                                     NOTICE

       Hewlett-Packard is making the current preliminary version 2.2 of
       USRLIB.EXE available to customers free of charge to help them in
       HP 48SX application development, under the following conditions:

       * The program USRLIB.EXE and the documentation file USRLIB.MAN are
       provided "as is," and are subject to change without notice.
       Hewlett-Packard Company make no warranty of any kind with regard
       to the software or documentation, including, but not limited to,
       the implied warranties of merchantability and fitness for a
       particular purpose.  Hewlett-Packard Company shall not be liable
       for any error or for incidental or consequential damages in
       connection with the furnishing, performance, or use of this
       software and documentation.

       * The program and documentation are copyrighted by Hewlett-
       Packard.  Customers may freely reproduce and distribute this
       material.  Sale of this material is prohibited without prior
       written permission of Hewlett-Packard Company.

       * The HP Customer Support department does not support the current
       version.  Questions, comments, defect reports, etc. should be
       directed to the Library Development conference on the HP
       Calculator Bulletin Board System.  All responses from Hewlett-
       Packard will normally be provided through that conference.

       * Software converted into libraries by USRLIB.EXE should be tested
       and qualified in its library form.  Discrepancies between the
       execution of the libraries and the execution of the original
       source directory contents should be reported via the Bulletin
       Board.

       Revised versions of the software and documentation will be posted
       on the Bulletin Board as they become available.  In particular,
       future versions will include less cryptic error messages, and
       better documention of the output listing information provided by
       the program.

       Version 2.2 of the program USRLIB.EXE is a preliminary version of
       this software.  Software compiled into libraries using this
       program should be thoroughly tested in its library form prior to
       any reproduction or distribution to end users.

       *****************************************************************






                                   -1-











       1.  INTRODUCTION


       USRLIB.EXE is an MS-DOS executable file that creates an HP 48
       library object from an HP 48 directory.  A library is similar to a
       directory in that both are collections of named objects.  However,
       a directory normally resides in main RAM memory and is intended
       for continuous modification and execution, whereas a library
       contains objects intended for execution only, and can be used from
       ROM as readily as from RAM.  A directory's objects are organized
       in a linked list requiring a sequential search for access; a
       library contains an address table that provides rapid execution
       access to its individual objects.


       1.1  Glossary of Terms

       Directory           HP48 directory object containing zero or more
                           variables.

       Variable            A named object contained within a directory,
                           accessed by means of a global name.

       Library             HP 48 library object containing zero or more
                           library commands.  Libraries include a text
                           title, a Library ID number, and optional
                           message tables and configuration code that is
                           executed at system halts.

       Library command     A named object within a library, which is the
                           library analog of a directory's variable.

       Global name         HP 48 global name object, execution of which
                           executes the object in the corresponding
                           (global) variable.

       XLIB name           HP 48 XLIB name object, execution of which
                           executes the corresponding library command.
                           An XLIB name plays the role for libraries that
                           a global name plays for directories.

       Library ID          A number in the range 0-7FFh that uniquely
                           identifies a library, and is used as an
                           argument for HP 48 commands that deal with
                           libraries as objects.  The following ranges
                           are defined for the ID numbers:








                                   -2-











                                  ID Range                    Purpose
                              Hex        Decimal

                             0 - 100       0 - 256
                           101 - 200     257 - 512   HP ROM-Based Applications
                           201 - 300     513 - 768   HP RAM-Based Applications
                           301 - 600    769 - 1536
                                                     Non-HP Applications
                                                     (numbers permanently
                                                     assigned by HP)
                           601 - 6FF   1537 - 1792
                           700 - 7FF   1792 - 2047   HP 48SX Command Line Use



       1.2  The Source Directory

       USRLIB uses an HP 48 directory object as the source file to define
       the output library.  The source directory may contain any number
       of variables, each of which is converted to a library command in
       the output library (unless specified otherwise; see $VARS,
       $VISIBLE and $HIDDEN, below).  The objects in the variables are
       translated as necessary so that any global names in the objects
       that correspond to variables in the source directory are converted
       to XLIB names.

       The source directory may contain subdirectories, but in that case
       the resulting library will not reflect the structure of the
       directory since a library structure is "flat."  If separate
       subdirectories contain variables with the same name, the uses of
       those names within the library will be correct, but the duplicated
       names will also be duplicated in the LIBRARY menu.  The names of
       the subdirectories themselves are not translated to library
       commands, and any use of those names in any of the other variables
       will result in an error during execution of USRLIB.

       The directory may also include the following special variables:


       $ROMID      Contains a real or binary number object representing
                   the Library ID that is to be given to the library.
                   This can be overridden by specifying -rrrrroooommmmiiiidddd on the
                   command line.  The ID should be in the range 769 -
                   1792 (301h - 6FFh).

                   The -r option must be specified from the command line
                   if no $ROMID is used.

       $TITLE      Contains a string to be used as the name of the
                   library.  This can be overridden by specifying -tttttiiiittttlllleeee
                   on the command line.  The first (up to) 5 characters
                   of the title are used for the LIBRARY menu label; the



                                   -3-











                   first 22 characters are displayed by REVIEW.

       $CONFIG     Contains an object to be executed at configuration
                   time.  If no $CONFIG variable is present, no
                   configuration entry will be generated.  In the current
                   version of USRLIB, $CONFIG is also translated to a
                   library command; to prevent this, it $CONFIG should be
                   declared as hidden (see below).

                   Note: the configuration code can generally NOT be
                   written in user-accessible commands.  Simple programs
                   such as << 123 ATTACH >> are OK, but more complicated
                   programs should take care to leave the stack
                   unchanged, and be sure NOT TO ERROR.

       $MESSAGE    Contains a list of names of variables that contain
                   strings to be combined into a message table. The
                   message numbers correspond to the list positions.

                   If no $MESSAGE is present, no message table will be
                   generated.

       $VISIBLE    Contains a list of names of variables to be converted
                   to user-accessible library commands.

                   By default, all variables will be translated to
                   library commands.  When the $VISIBLE list is present,
                   only the names in this list are used as XLIB name
                   table entries in the library. An empty list is
                   allowed, meaning that no XLIB name entries are
                   created.

       $HIDDEN     Contains a list of names of variables that are to be
                   converted to null-named objects in the library, and so
                   hidden from the library user.

                   When the $HIDDEN list is present, those names listed
                   are not entered in the library XLIB name table.  If
                   both $VISIBLE and $HIDDEN are present, only the
                   $HIDDEN list will be used.

       $VARS       Contains a list of variables that should remain RAM-
                   based, i.e., the stored objects are not included in
                   the library, and no XLIB name entries are made for
                   their names.  All other variables in the source
                   directory names are included as library commands.

       Multiple instances are permitted of the declaration variables
       $VARS, $HIDDEN, and $VISIBLE variables, in various subdirectories
       of the source directory.  A particular variable is declared as a
       RAM variable, hidden, etc., if its name is entered in any of the



                                   -4-











       relevant declaration variables anywhere in the current path
       defined by the variable's location. That is, a variable XXX found
       in any subdirectory will be hidden if XXX is in a list stored in
       $HIDDEN in the top level of the source directory; but YYY in the
       top level will not be hidden even if YYY is present in a $HIDDEN
       list in a subdirectory.

       Not all program objects that execute correctly from global
       variables are directly convertible into libraries.  In general, no
       checks can be made for such errors, and USRLIB does not attempt to
       do so.  Here are some known pitfalls:

          o+ Since a library cannot be modified, no library command may be
            the target of a STO or PUT operation.

          o+ XLIB names are not usable in all contexts in which global
            names are valid arguments.  This can cause constructs that
            reference a named object to fail.  For example,

                                      'A' 5 GETI

            where A is a list will not work when A is converted to an
            XLIB name.  Instead use

                                   'A' EVAL 5 GETI

            or better yet

                                      A 5 GETI

            XLIB names are not valid as formal variables in algebraics,
            or as the independent variable for plotting or solving.
            Names intended to be used as such should be declared as
            global using $VARS or the -v option.

          o+ ->STR applied to a global name that is converted to a
            ``hidden'' library command (see $HIDDEN) returns a null
            string.

          o+ Embedded directories (entered as DIR...END) within lists and
            programs are not translated except for their first object.













                                   -5-











       1.3  Library Creation

       The process of library creation and activation can be summarized
       as follows.

         1.  Develop an application consisting of any number of programs
             and other objects, and collect these in one single-level
             directory in the HP 48.

         2.  Using Kermit binary transfer, send the directory to a PC.

         3.  Execute USRLIB, using the directory as the source file.  In
             this step, you also assign a library ID and a library title
             to the output library.

         4.  Transfer the USRLIB output library object back to the HP 48,
             to a variable in any convenient directory.

         5.  Recall the library object from the variable to which it was
             transferred, and then store it in a RAM port (:n:x STO,
             where n is the port number, and x is any number).  After
             storing the library, you can purge the original copy in the
             variable to save memory.

         6.  Turn the HP 48 off, then on.  This adds the new library to
             the system library table, and gives the library a chance to
             execute its own configuration program, if any.  (The HP 48
             will execute a system halt automatically at this stage, so
             you should save any stack objects or PICT first if you wish
             to recover them.)  The LIBRARY menu will now contain a menu
             entry labeled with the library's ID number in the PORTn
             submenu.

         7.  Activate the directory in which you wish the library's
             commands to be accessible, then execute nnn ATTACH, where
             nnn is the library ID.  Any number of libraries can be
             attached to the HOME directory; subdirectories may have one
             library attached to each.  The main LIBRARY menu will now
             contain a menu key labeled by the library's title.

       To remove a library, activate its associated directory and execute
       nnn DETACH.  Then execute :n:ID PURGE to remove the library from
       port n.  (You will notice a brief jump in the display when you
       execute the PURGE.  This is normal and harmless.)










                                   -6-











       2.  Instructions

       (In the following, bbbboooolllldddd text represents user-supplied text.  Text
       appearing in brackets [ ] denotes optional entries. In actual
       entries, the [ ] should not be used.)

       Syntax:
               USRLIB [-options] ddddiiiirrrrffffiiiilllleeee [ lllliiiibbbbffffiiiilllleeee [ ssssuuuummmmffffiiiilllleeee ] ]


       ddddiiiirrrrffffiiiilllleeee   is the name of the source file, which must contain a
                 binary image of an HP48 directory or a backup object
                 containing a directory.

       LLLLiiiibbbbffffiiiilllleeee   is a file to contain the output library object.

       ssssuuuummmmffffiiiilllleeee   This is a textual summary of the names that were
                 translated.  The following information is given for each
                 object:  user name, type, offset into the lllliiiibbbbffffiiiilllleeee file,
                 XLIB numbers, whether it can be used in an algebraic,
                 and whether it is visible.

                 Similarly, a list of message numbers and messages and a
                 summary of the space requirements is given.

       SSSSuuuummmmffffiiiilllleeee and the optional lllliiiissssttttffffiiiilllleeee (see OPTIONS below) may be
       redirected to stdout by using '-' for the output file name.


       2.1  Options

       The following options may be included in the USRLIB command line:


       -dlllliiiissssttttffffiiiilllleeee  lllliiiissssttttffffiiiilllleeee will contain a text listing of the contents
                   of each object in the input directory.


       -hhhhheeeeaaaaddddeeeerrrr    Use hhhheeeeaaaaddddeeeerrrr for the library object header (for file
                   transfer).


       -llllliiiissssttttffffiiiilllleeee  lllliiiissssttttffffiiiilllleeee will contain a text listing of the contents
                   of each object in the output library. Occurrances of
                   "ID'name'<--" indicate translation of an name (ID)
                   into an XLIB or a message table reference.


       -rrrrroooommmmiiiidddd     Set decimal Library ID (see $ROMID above).





                                   -7-











       -tttttiiiittttlllleeee     Use ttttiiiittttlllleeee for the library title (see $TITLE above).


       -vnnnnaaaammmmeeee      Declare nnnnaaaammmmeeee as a RAM variable name (see $VARS above).


       2.2  Restrictions

         1.  The total library output file cannot be larger than 128K
             bytes.

         2.  Message strings must be less than 64K bytes each.


       2.3  Example

       The following example combines the programs PAD, PRESERVE, and a
       modified version of BDISP from the Owner's Manual into a library
       application.

       The variables $TITLE, $ROMID, $VISIBLE, and $VARS control the
       creation of the library.  The variable $CONFIG contains a program
       which attaches the library to the HOME directory whenever a System
       Halt occurs.

       BDISP has been modified to store the hex version of the input
       number in the variable LSTN.  The $VARS variable specifies that
       LSTN will be a user variable (found in the VAR menu), and should
       not be compiled into the library.

       The programs PAD and PRESERVE are called by BDISP. Since the
       control variable $VISIBLE only specifies BDISP, all other
       variables are hidden (or left as globals as specified by the $VARS
       variable).




















                                   -8-











       In ASCII form, a directory containing everything required for the
       complete library application looks like this:
       %%HP: T(3)A(D)F(.);
       DIR
         PRESERVE
           << RCLF -> f
             << EVAL f STOF >>
           >>
         PAD
           << ->STR
             WHILE
               DUP SIZE 22 <
             REPEAT
               " " SWAP +
             END
           >>
         BDISP
           <<
             << DUP -55 CF
               IFERR R->B
               THEN
               END -> n
               << CLLCD
                 << BIN >>
                 << OCT >>
                 << DEC >>
                 << HEX >>
                 1 4
                 FOR j
                   EVAL n ->STR PAD
                   j DISP
                 NEXT n 'LSTN' STO
               >> 3 FREEZE
             >> PRESERVE
           >>
         $CONFIG  << HOME 800 ATTACH >>
         $ROMID   800
         $TITLE   "BDLIB :Binary Display"
         $VISIBLE { BDISP }
         $VARS    { LSTN }
       END













                                   -9-











       2.4  Error Messages

       In the following error messages, words shown in parentheses
       represent values that indicate source-specific quantities. (path)
       represents the path within the source directory to the variable
       causing the error, in the form name1/name2/... , where the names
       are the subdirectory names (on the HP 48SX, the path would be a
       list { name1 name2 ... }).

          "Insufficient Memory"  - Memory is constantly being allocated
                                   for various compiler needs.

          "Unexpected EOF on Input"  - EOF was found when more nibbles
                                       were expected.

          "USRLIB: Cannot open"  - The source file can not be opened.

          "USRLIB: - not legal for input"  - "-" (stdin) can't be used
                                             for input.

          "ROMID must be in range 769 - 1792"

          "Must have either -r romid or $ROMID"  - No library ID was specified.

          "Need either BAK of a directory or a directory"

          "BAK object does not contain directory"

          "Directory is empty"

          "Object is not a string: (path)/$TITLE"

       The next three messages may occur when ROMID is specified in the
       variable $ROMID.

          "Illegal Real value for (path)/$ROMID: (value)"

          "Illegal Binary value for (path)/$ROMID: (value)"

          "Object not Real or Binary: (path)/$ROMID"

       The next two messages may occur when a $CONFIG variable (or two)
       are specified.

          "Object not program: (path)/$CONFIG"

          "$CONFIG redefined: (path)/$CONFIG"







                                   -10-











       The next message may occur any time a string (variable name or
       message) is read.

          "Variable name or message too long (>65535)"

       The next two messages may occur when a name list is being read.  The
       $MESSAGE, $VISIBLE, $HIDDEN, and $VARS variables are all name lists.

          "Object is not a list: (path)/name"

          "Non-ID found in list:  (path)/name"

          "Message object not found: (name)"

          "Loss of object synchronism between passes: (path)/(name)"
             - (path)/(name) is replaced with the object where out-of-sync
             was discovered.

          "Name must not exceed 16 characters: (path)/(name)"
             - Library object names are limited to 16 characters.

          "Keyword cannot resolve to a directory: (path)/(name)"
             - Subdirectory names cannot be included in other directory
               objects' definitions.

       The next two messages may occur as message objects (indicated in the
       $MESSAGE list) are being converted into a message table.

          "Message object is not a string: (path)/(name)"

          "Multiple definitions for message (path)/(name)"

       The next three messages may occur as the final library object is being
       written to the output file.

          "Library image length is 0.  LIB FILE NOT WRITTEN!"

          "Max image size is 256K nibbles ... image is (value) nibbles.
           LIB FILE NOT WRITTEN!"

          "Unsucessful write to library file"  - Unknown error writing to
                                                 library file.












                                   -11-